.\" $Id: PAPI_get_overflow_event_index.3,v 1.4 2004/10/01 18:44:06 terpstra Exp $
.TH PAPI_get_overflow_event_index 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_get_overflow_event_index \- converts an overflow vector into an array of indexes to overflowing events

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_get_overflow_event_index(int " EventSet ", long_long " overflow_vector ", int *" array ", int *" number ");"
.fi
.B Fortran Interface
.nf
.I Not implemented
.fi

.SH DESCRIPTION
.LP
.B PAPI_get_overflow_event_index
decomposes an overflow_vector into an event index array in which the first element 
corresponds to the least significant set bit in overflow_vector and so on. 
Based on overflow_vector, the user can only tell which physical counters overflowed. 
Using this function, the user can map overflowing counters to specific events in the 
event set. An array is used in this function to support the possibility of multiple
simultaneous overflow events. 

.SH ARGUMENTS
.I EventSet 
--  an integer handle to a PAPI event set as created by
.BR "PAPI_create_eventset" (3)
.LP
.I overflow_vector 
--  a vector with bits set for each counter that overflowed. 
This vector is passed by the system to the overflow handler routine.
.LP
.I *array 
-- an array of indexes for events in
.I EventSet.
No more than 
.I *number
indexes will be stored into the 
.I array.
.LP
.I *number 
-- On input the variable determines the size of the 
.I array.
 On output the variable contains the number of indexes in the
.I array.
.LP
Note that if the given
.I *array
is too short to hold all the indexes correspond to the set bits in the overflow_vector the
.I *number
variable will be set to the size of 
.I array.

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid. This could occur if the
.I overflow_vector 
is empty (zero), if the
.I array
or
.I number
pointers are NULL, if the value of
.I number
is less than one, or if the 
.I EventSet
is empty.
.TP
.B "PAPI_ENOEVST"
The 
.I EventSet
specified does not exist.
.TP

.SH EXAMPLES
Create a user defined overflow handler routine that prints diagnostic
information about the overflow:
.nf
.if t .ft CW
void handler(int EventSet, void *address, long_long overflow_vector, void *context)
{
  int Events[4], number, i;
  int total = 0, retval;
  
   printf("Overflow #%d\n  Handler(%d) Overflow at %p! vector=0x%llx\n",
     total, EventSet, address, overflow_vector);
   total++;
   number = 4;
   retval = PAPI_get_overflow_event_index(EventSet,
                 overflow_vector, Events, &number);
   if(retval == PAPI_OK)
     for(i=0; i<number; i++) printf("Event index[%d] = %d", i, Events[i]);
}
.if t .ft P
.fi

.SH BUGS
This function may not return all overflowing events if used with 
software-driven overflow of multiple derived events.

.SH SEE ALSO
.BR PAPI_overflow "(3)" 
